home *** CD-ROM | disk | FTP | other *** search
/ Pascal Super Library / Pascal Super Library (CW International)(1997).bin / PGM_TOOL / TPRCDR10 / READ.ME < prev    next >
Text File  |  1994-03-11  |  11KB  |  204 lines
  1. TPRecDir.TPU Copyright (c) 1993, 1994 by Tony G. Papadimitriou, M.S.
  2.  
  3. Instructions for using the TPRecDir.TPU in your own programs.
  4.  
  5. Hi,
  6.  
  7. This archive contains the following files:
  8.  
  9. CRC $7197BD52 (        1376 bytes) for MAKEFILE        for use with MAKE
  10.               (       10950 bytes) for READ.ME         this file
  11. CRC $5A433BAD (        5813 bytes) for TPRECDIR.INT    TPRecDir interface
  12. CRC $E0FF4E83 (        9648 bytes) for TPRECDIR.TPU    TP60 TPU
  13. CRC $CBDF55DC (       27424 bytes) for TPUTILS.TPU     TP60 TPU used in examples
  14. CRC $B5708767 (       12384 bytes) for TPRECDIR.TP7    TP70 TPU
  15. CRC $89C8529B (       40528 bytes) for TPUTILS.TP7     TP70 TPU used in examples
  16. CRC $DBF2FC3E (        2098 bytes) for COUNT.PAS       example
  17. CRC $895BD4CD (        4538 bytes) for EXTS.PAS        example
  18. CRC $6CD3EA3D (        6929 bytes) for FD.PAS          example
  19. CRC $BF842E43 (        3580 bytes) for LDIR.PAS        example
  20. CRC $A1530980 (        3242 bytes) for MCOPY.PAS       example
  21. CRC $081C27E3 (        2198 bytes) for WHERE.PAS       example
  22. CRC $BEBBA27D (        2983 bytes) for ZAPDIR.PAS      example
  23.  
  24. The TPU file included in this archive is a Turbo Pascal 6.0 unit that allows
  25. you to recursively act on any file in the supplied path.  This is done by
  26. setting up a little routine that gets called from the unit in a manner
  27. similar to that the SORT unit by Borland operates.
  28.  
  29. The source code is not available at this time.
  30.  
  31. The interface of the unit is found in the file TPRECDIR.INT
  32.  
  33. An additional unit is included that provides some routines to the example
  34. programs.  No documentation is provided for it though.
  35.  
  36. There are plenty of comments to make any further documentation needless.  
  37. Also, there are several test programs that demonstrate how to use the 
  38. various routines in the TPRECDIR unit.
  39.  
  40. However, here's a few extra words.
  41.  
  42. There are several routines in this unit.  Only one is actually needed to do 
  43. the work and the other four are just there to make life easier if you ever 
  44. need to use them.  Most won't even get linked into your programs if you 
  45. don't use them because of Turbo Pascal's smart linking.
  46.  
  47. The main function's header looks like this:
  48.  
  49. function ForEachFileIn(workPath,             { beginning directory, e.g., 'E:\TMP' }
  50.                        fileMask: String;     { file mask, e.g., '*.BAK' }
  51.                        attr: Word;           { file attribute to match }
  52.                        monitorEsc: Boolean;  { if True, an ESC press will cause immediate return }
  53.                        recurseOn: Boolean;   { if True, it will recurse subdirectories }
  54.                        userRoutine: pointer): Longint;
  55.  
  56. It could be called as a procedure (with the X option turned on) if you don't
  57. care to know how many matches there were.  Any errors will be reported by
  58. the boolean type variable errorsFound.  No error codes will be given.  You
  59. can check for error codes in your own routine depending on what you're
  60. trying to do.
  61.  
  62. The parameters are pretty straight forward.  The only possibly confusing
  63. part is the one about the userRoutine.  This routine is a function that
  64. returns True on success and False otherwise.  It has a single parameter
  65. which is of type SearchRec (found in the Dos standard unit).  On entry, the
  66. SearchRec variable you define will hold the information about the next match
  67. whether this is a directory or a file.  Any directory that matches the
  68. attribute specified and any file that matches both the attribute specified 
  69. and the file mask will be passed to your routine through the SearchRec 
  70. variable.  You can check its attribute and act on it accordingly.
  71.  
  72. Since this routine uses recursion, you ought to be careful about allocating
  73. enough stack if your trees tend to get too deep.  Also, you should be aware
  74. of the order the files are passed to your routine which is the same order
  75. they appear in the directory with the exception that any directories found
  76. in the middle will be processed before the remaining of the current
  77. directory and likewise for the ones below it.
  78.  
  79. When a subdirectory is finished being recursed it will have its name passed
  80. to your routine so that you may process the directory itself, e.g., you may
  81. want to remove it, and this is the only time you could anyway because all
  82. the files and directories in it have already been processed and by now you
  83. have already had the chance to erase them.
  84.  
  85. This unit grabs the exit routine of your program and upon either normal or 
  86. abnormal termination will restore the previous directories in all drives 
  87. involved, so you don't need to keep track of the current directory in any of 
  88. the drives involved.
  89.  
  90. The next two routines can be used to check a mask prior to passing it to the
  91. ForEachFileIn routine for validity of the characters it contains and for 
  92. checking if the mask is equivalent to a global '*.*' which can be very 
  93. dangerous in many situations, such as when one is trying to delete the root
  94. and everything under it using *.*.  Here are the headers of those two
  95. routines.  They both take as a parameter a single string that holds the mask
  96. and return True on a positive check and False otherwise.
  97.  
  98. { ╔═══════════╤════════════════════════════════════════════════╗
  99.   ║ Routine   │ IsGlobalMask                                   ║
  100.   ║ Purpose   │ Return True if mask passed is equivalent to    ║
  101.   ║           │ '*.*', such as '*??.???' for example.          ║
  102.   ╚═══════════╧════════════════════════════════════════════════╝ }
  103. function IsGlobalMask(mask: String): Boolean;
  104.  
  105. { ╔═══════════╤════════════════════════════════════════════════╗
  106.   ║ Routine   │ IsValidMask                                    ║
  107.   ║ Purpose   │ Return True if mask passed does NOT contain    ║
  108.   ║           │ any of the following characters:               ║
  109.   ║           │ < > = , ; : [ ] / \ +                          ║
  110.   ╚═══════════╧════════════════════════════════════════════════╝ }
  111. function IsValidMask(mask: String): Boolean;
  112.  
  113. The next routine makes a very simple comparison and returns the result as a 
  114. boolean value.  It compares two attributes and returns true if any of their 
  115. bits are in the same position.  This is useful for checking if a file is of 
  116. a given attribute, e.g. if AttributeMatches(rec.attr,Directory) then.
  117.  
  118. { ╔═══════════╤════════════════════════════════════════════════╗
  119.   ║ Routine   │ AttributeMatches                               ║
  120.   ║ Purpose   │ Return True if attr1 and attr2 have any bits   ║
  121.   ║           │ in common.                                     ║
  122.   ╚═══════════╧════════════════════════════════════════════════╝ }
  123. function AttributeMatches(attr1,attr2: Word): Boolean;
  124.  
  125. Another routine lets you know if a filename (without path, i.e., in the form 
  126. FILENAME.EXT) matches a given mask.  It is used, like some of the rest of
  127. the routines, internally but can also be useful as a standalone routine for
  128. other purposes.
  129.  
  130. { ╔═══════════╤════════════════════════════════════════════════╗
  131.   ║ Routine   │ MaskMatches                                    ║
  132.   ║ Purpose   │ Return True if filename can be matched by mask ║
  133.   ║ Note(s)   │ Mask may contain multiple masks delimited by ; ║
  134.   ╚═══════════╧════════════════════════════════════════════════╝ }
  135. function MaskMatches(filename,mask: String): Boolean;
  136.  
  137. Two more routines are provided to let you easily get the mask part from a 
  138. [command line] path specification and the directory path itself.  They are:
  139.  
  140. { ╔═══════════╤════════════════════════════════════════════════╗
  141.   ║ Routine   │ GetMask                                        ║
  142.   ║ Purpose   │ Return the multiple masks from a given argument║
  143.   ╚═══════════╧════════════════════════════════════════════════╝ }
  144. function GetMask(path: String): String;
  145.  
  146. { ╔═══════════╤════════════════════════════════════════════════╗
  147.   ║ Routine   │ GetPath                                        ║
  148.   ║ Purpose   │ Return the path/no masks from a given argument ║
  149.   ╚═══════════╧════════════════════════════════════════════════╝ }
  150. function GetPath(path: String): String;
  151.  
  152. Finally, the routine MkChDir is used to create and change to a path in a
  153. single step.  Note that the complete path can be created with this routine
  154. even if no part of it exists.  For example, assuming there's no directory
  155. D:\TMP on your disk, doing a MkChDir('D:\TMP\MISC\WORK\DATA') will create
  156. four directories (D:\TMP, D:\TMP\MISC, D:\TMP\MISC\WORK, and
  157. D:\TMP\MISC\WORK\DATA) and then change to the last one.  If the process
  158. fails half-way through, you will be placed inside the last successfully
  159. created/changed to directory and the function will return False.  Here's the
  160. header for this function.
  161.  
  162. { ╔═══════════╤════════════════════════════════════════════════╗
  163.   ║ Routine   │ MkChDir                                        ║
  164.   ║ Purpose   │ Create (if non-existant) dir tree and change   ║
  165.   ║           │ to it. Returns True on success.                ║
  166.   ╚═══════════╧════════════════════════════════════════════════╝ }
  167. function MkChDir(dir: String): Boolean;
  168.  
  169. Note: Any time you need to use a mask in either the MaskMatches or the
  170.       ForEachFileIn routines, you can use multiple masks by separating them
  171.       with semi-colons, e.g., use '*.BAK;*.OLD' to match both files with a
  172.       .BAK extension and files with a .OLD extension in a single pass.
  173.  
  174. Several bugs have been fixed!  If you find any yourself, let me know.
  175.  
  176. If you need more help, study the example programs until you figure them out.
  177. It shouldn't take long!
  178.  
  179. Hope it comes in handy!  Let me know if you find any bugs or have problems
  180. with it in general.  Also, if you need to suggest improvements, feel free to
  181. do so at the address below.
  182.  
  183. ╔═══════════════════════════════════════════════════════════════════════════╗
  184. ║           Comments to the author may be directed at the address:          ║
  185. ║                                                                           ║
  186. ║                            Tony G. Papadimitriou                          ║
  187. ║                               P.O. Box 14386                              ║
  188. ║                                Athens 115 10                              ║
  189. ║                                   GREECE                                  ║
  190. ╚═══════════════════════════════════════════════════════════════════════════╝
  191.  
  192. Tony P.
  193.  
  194. LEGAL NOTICE:
  195.  
  196. This software is Freeware which means it is NOT public domain but distributed
  197. freely without money.  Its electronic distribution through BBSs or other such
  198. means is encouraged provided no money is requested for its acquisition.
  199.  
  200. Also, it is forbidden to distribute this software should this file or any of
  201. the remaining files change in any way or be omitted from the archive.
  202.  
  203.                                           Tony G. Papadimitriou, M.S.
  204.